<!DOCTYPE html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Tutorial collection &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Data-flow of tutorial text" href="tutorial-text-dataflow.html" />
    <link rel="prev" title="Compiling a tutorial from a Git repository" href="fromgitrepo.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../../index.html"><li>Help</li></a>
    <a href="../../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="tutorial-collection">
<h1>Tutorial collection<a class="headerlink" href="#tutorial-collection" title="Link to this heading">¶</a></h1>
<p>On launching the Pytch IDE, the user has a choice of tutorials.  To
know what tutorials are available, the IDE loads the file
<code class="docutils literal notranslate"><span class="pre">tutorials-index.html</span></code> and uses it to populate the <em>List of
tutorials</em> pane.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">pytchbuild-gather-tutorials</span></code> utility builds this
<code class="docutils literal notranslate"><span class="pre">tutorials-index.html</span></code> file and includes it in the resulting
zipfile.  To know what tutorials belong in the collection, it reads
the file <code class="docutils literal notranslate"><span class="pre">index.yaml</span></code> in the root of the <code class="docutils literal notranslate"><span class="pre">pytch-tutorials</span></code> repo’s
working directory.  See below for the workflow for changing this file.
The utility can also, if requested, create a new <em>release</em> of the
tutorial collection.</p>
<section id="creating-a-zipfile-of-all-tutorials">
<h2>Creating a zipfile of all tutorials<a class="headerlink" href="#creating-a-zipfile-of-all-tutorials" title="Link to this heading">¶</a></h2>
<p>Running the command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pytchbuild</span><span class="o">-</span><span class="n">gather</span><span class="o">-</span><span class="n">tutorials</span> <span class="o">-</span><span class="n">o</span> <span class="o">/</span><span class="n">tmp</span><span class="o">/</span><span class="n">tutorials</span><span class="o">.</span><span class="n">zip</span>
</pre></div>
</div>
<p>will read the current working copy of the <code class="docutils literal notranslate"><span class="pre">index.yaml</span></code> file, and use
it to create the zipfile given by the <code class="docutils literal notranslate"><span class="pre">-o</span></code> argument.</p>
</section>
<section id="structure-of-tutorial-list-html">
<span id="tutorial-index-html-structure"></span><h2>Structure of tutorial list HTML<a class="headerlink" href="#structure-of-tutorial-list-html" title="Link to this heading">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">tutorial-index.html</span></code> file has the following structure:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>&lt;div class=&quot;tutorial-index&quot;&gt;
  &lt;div class=&quot;tutorial-summary&quot; data-tutorial-name=&quot;bunner&quot;&gt;
    &lt;p class=&quot;image-container&quot;&gt;
      &lt;img alt=&quot;Screenshot&quot; src=&quot;summary-screenshot.png&quot;/&gt;&lt;/p&gt;
    &lt;h1&gt;Bunner — a Frogger-like game&lt;/h1&gt;
    &lt;p&gt;In this tutorial we&#39;ll ...&lt;/p&gt;
  &lt;/div&gt;
  &lt;div class=&quot;tutorial-summary&quot; data-tutorial-name=&quot;boing&quot;&gt;
    &lt;p class=&quot;image-container&quot;&gt;
      &lt;img alt=&quot;Screenshot&quot; src=&quot;summary-screenshot.png&quot;/&gt;&lt;/p&gt;
    &lt;h1&gt;Boing — a Pong-like game&lt;/h1&gt;
    &lt;p&gt;This tutorial shows you ...&lt;/p&gt;
  &lt;/div&gt;
  &lt;!-- DIVs for other tutorials --&gt;
&lt;/div&gt;
</pre></div>
</div>
</section>
<section id="archive-of-releases">
<h2>Archive of releases<a class="headerlink" href="#archive-of-releases" title="Link to this heading">¶</a></h2>
<p>Each tutorial is developed in its own branch, allowing history to be
re-written while the tutorial is being developed.</p>
<p>We would like to ensure reproducibility for the tutorials, in that we
would like to be able to:</p>
<ul class="simple">
<li><p>go back to a particular history of some individual tutorial;</p></li>
<li><p>remember what tutorials, and with what histories, were in the
collection at different times.</p></li>
</ul>
<p>Both needs are met by having a <code class="docutils literal notranslate"><span class="pre">releases</span></code> branch, <em>which authors do
not directly commit to</em>.  Instead, the workflow for releasing a new
version of the tutorial collection is as follows.</p>
</section>
<section id="releasing-a-new-version-of-the-tutorial-collection">
<h2>Releasing a new version of the tutorial collection<a class="headerlink" href="#releasing-a-new-version-of-the-tutorial-collection" title="Link to this heading">¶</a></h2>
<p>The maintainer checks out the branch <code class="docutils literal notranslate"><span class="pre">release-recipes</span></code>, which
contains just the <code class="docutils literal notranslate"><span class="pre">index.yaml</span></code> file.  The maintainer might be
releasing a new version of the tutorial collection because:</p>
<ul class="simple">
<li><p>one of the individual tutorials has been revised — perhaps its
author has edited the wording of the tutorial text, or re-arranged
the history of the commits developing the <code class="docutils literal notranslate"><span class="pre">code.py</span></code> file;</p></li>
<li><p>the collection itself has been revised — perhaps we have added a new
tutorial, or removed an old one, or changed the order of the
tutorials in the collection.</p></li>
</ul>
<p>In the first case, the <code class="docutils literal notranslate"><span class="pre">index.yaml</span></code> file does not need to change.
(Unless the author renamed the branch containing the tutorial in
question.)</p>
<p>In the second case, it does, and so the maintainer edits
<code class="docutils literal notranslate"><span class="pre">index.yaml</span></code> and commits that change to the <code class="docutils literal notranslate"><span class="pre">release-recipes</span></code>
branch.</p>
<p>Either way, the maintainer runs, from somewhere in the tutorials
repo:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pytchbuild</span><span class="o">-</span><span class="n">gather</span><span class="o">-</span><span class="n">tutorials</span> <span class="o">--</span><span class="n">make</span><span class="o">-</span><span class="n">release</span> <span class="o">-</span><span class="n">o</span> <span class="o">/</span><span class="n">tmp</span><span class="o">/</span><span class="n">tutorials</span><span class="o">.</span><span class="n">zip</span>
</pre></div>
</div>
<p>This will produce the tutorials bundle zipfile as usual, but then also
make a commit to the <code class="docutils literal notranslate"><span class="pre">releases</span></code> branch.  The commit to <code class="docutils literal notranslate"><span class="pre">releases</span></code>
has a hard-coded generic commit message.  Ideally, the maintainer will
check out the <code class="docutils literal notranslate"><span class="pre">releases</span></code> branch and reword its tip commit’s message
to something more meaningful.  This can be done with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">commit</span> <span class="o">--</span><span class="n">amend</span> <span class="o">--</span><span class="n">only</span>
</pre></div>
</div>
<p>on the command line, or <code class="docutils literal notranslate"><span class="pre">cw</span></code> (Commit reWord) if using <a class="reference external" href="https://magit.vc/">Magit</a>.  Rewording the commit’s message must be done
<em>before</em> pushing upstream, to avoiding rewriting upstream history.</p>
<p>If the working copy of the <code class="docutils literal notranslate"><span class="pre">index.yaml</span></code> file differs from the
version stored at the tip of <code class="docutils literal notranslate"><span class="pre">release-recipes</span></code>, an error will be
thrown.  This is to guard against creating an inconsistent release.</p>
</section>
<section id="creating-a-bundle-from-a-releases-commit">
<h2>Creating a bundle from a <code class="docutils literal notranslate"><span class="pre">releases</span></code> commit<a class="headerlink" href="#creating-a-bundle-from-a-releases-commit" title="Link to this heading">¶</a></h2>
<p>For full reproducibility of the tutorials bundle, the
<code class="docutils literal notranslate"><span class="pre">pytchbuild-gather-tutorials</span></code> tool can also build a zipfile from the
information stored in a particular <code class="docutils literal notranslate"><span class="pre">releases</span></code> commit.  Supposing the
commit of interest on <code class="docutils literal notranslate"><span class="pre">releases</span></code> is tagged <code class="docutils literal notranslate"><span class="pre">v2.3.1</span></code>, a bundle
matching that point can be made with:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pytchbuild-gather-tutorials<span class="w"> </span>--from-release<span class="w"> </span>v2.3.1<span class="w"> </span>-o<span class="w"> </span>/tmp/tuts-2.3.1.zip
</pre></div>
</div>
</section>
<section id="verifying-branch-heads">
<h2>Verifying branch heads<a class="headerlink" href="#verifying-branch-heads" title="Link to this heading">¶</a></h2>
<p>When the <code class="docutils literal notranslate"><span class="pre">pytch-tutorials</span></code> repo is on the <code class="docutils literal notranslate"><span class="pre">releases</span></code> branch, there
is a file <code class="docutils literal notranslate"><span class="pre">build-sources.yaml</span></code> at the root of the repository.
(<a class="reference internal" href="#build-sources-yaml"><span class="std std-ref">Details here</span></a>.)  The tool</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pytchbuild-verify-branch-heads
</pre></div>
</div>
<p>compares the commit SHAs recorded in that file with the current tips
of the branches recorded in the <code class="docutils literal notranslate"><span class="pre">index.yaml</span></code> file and reports on any
differences.</p>
</section>
<section id="details-commits-on-releases">
<h2>Details: Commits on <code class="docutils literal notranslate"><span class="pre">releases</span></code><a class="headerlink" href="#details-commits-on-releases" title="Link to this heading">¶</a></h2>
<p>A commit to the <code class="docutils literal notranslate"><span class="pre">release</span></code> branch has many parents.  Its first parent
is the previous state of the <code class="docutils literal notranslate"><span class="pre">release</span></code> branch, as usual.  Its other
parents are, first, the then-current tip of the <code class="docutils literal notranslate"><span class="pre">release-recipes</span></code>
branch, followed by the then-current tips of the tutorials’ branches,
i.e., as they were when they were used to build the tutorial
collection.  In this way, tutorials’ individual historical commit
histories are preserved.</p>
<section id="the-build-sources-yaml-file">
<span id="build-sources-yaml"></span><h3>The <code class="docutils literal notranslate"><span class="pre">build-sources.yaml</span></code> file<a class="headerlink" href="#the-build-sources-yaml-file" title="Link to this heading">¶</a></h3>
<p>To ease the reconstruction of the historical state of the tutorial
bundle, the <code class="docutils literal notranslate"><span class="pre">--make-release</span></code> option also writes a file
<code class="docutils literal notranslate"><span class="pre">build-sources.yaml</span></code> into the root of the repository tree for the
new commit to <code class="docutils literal notranslate"><span class="pre">releases</span></code>.  This file contains information on each
contribution to the tutorial bundle: its user-visible name, the name
of the branch as it was when creating the bundle, the directory name
containing the tutorial’s files, and the commit oid of the tip of that
branch.  To some extent this duplicates the information in the list of
parents of the commit, but in a more convenient form.</p>
</section>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../webapp/user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../vm/user/index.html">Writing Pytch programs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../developer.html">Developer documentation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../developer/development-setup.html">Development setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/design-overview.html">Design overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../vm/developer/index.html">VM</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../webapp/developer/index.html">Webapp</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../medialib/developer/index.html">Media library</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/index.html">Website</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Tools</a><ul class="current">
<li class="toctree-l3 current"><a class="reference internal" href="../index.html#tutorial-compiler-and-related-tools">Tutorial compiler and related tools</a></li>
<li class="toctree-l3"><a class="reference internal" href="../index.html#assembly-of-website-bundle">Assembly of website bundle</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../source-build.html">Source and build information</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../releases/changelog.html">Changelog</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>